NewGDevice

NewGDevice
Header:	Quickdraw.h		Carbon status:	Supported

Creates a new GDevice structure.

GDHandle NewGDevice (
    SInt16 refNum, 
    SInt32 mode
);

Parameter descriptions

refNum: Reference number of the graphics device for which you are creating a GDevice structure. For most video devices, this information is set at system startup.
mode: The device configuration mode. Used by the screen driver, this value sets the pixel depth and specifies color or black and white.

function result: A handle to the new GDevice structure. If the request is unsuccessful, NewGDevice returns NULL.

DISCUSSION

Generally, you do not need to use NewGDevice, because Color QuickDraw uses this function to create GDevice structures for your application automatically. When the system starts up, it allocates and initializes one handle to a GDevice structure for each video device it finds. When you use the NewGWorld function, QuickDraw automatically creates a GDevice structure for the new offscreen graphics world.

For the graphics device whose driver is specified in the refNum parameter and whose mode is specified in the mode parameter, the NewGDevice function allocates a new GDevice structure and all of its handles, and then calls the InitGDevice function to initialize the structure.

NewGDevice allocates the new GDevice structure and all of its handles in the system heap, and the NewGDevice function sets all attributes in the gdFlags field of the GDevice structure to FALSE. If your application creates a GDevice structure, use the SetDeviceAttribute function to change the flag bits in the gdFlags field of the GDevice structure to TRUE. Your application should never directly change the gdFlags field of the GDevice structure. Instead, use only the SetDeviceAttribute function.

If your application creates a GDevice structure without a driver, set the mode parameter to –1. In this case, InitGDevice cannot initialize the GDevice structure, so your application must perform all initialization of the structure. A GDevice structure’s default mode is defined as 128. This is assumed to be a black-and-white mode. If you specify a value other than 128 in the mode parameter, the structure’s gdDevType bit in the gdFlags field of the GDevice structure is set to TRUE to indicate that the graphics device is capable of displaying color.

The NewGDevice function does not automatically insert the GDevice structure into the device list. In general, your application should not create GDevice structures, and if it ever does, it should never add them to the device list.

If your program uses NewGDevice to create a graphics device without a driver, InitGDevice does nothing; instead, your application must initialize all fields of the GDevice structure. After your application initializes the color table for the GDevice structure, call the Color Manager function MakeITable to build the inverse table for the graphics device.

SPECIAL CONSIDERATIONS

The NewGDevice function may move or purge memory blocks in the application heap; do not call this function at interrupt time.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.